KCFindGenericPassword

KCFindGenericPassword
Header:	Keychain.h		Carbon status:	Under Evaluation

Finds the first generic password in the default keychain matching specified parameters.

OSStatus KCFindGenericPassword (
    StringPtr serviceName, 
    StringPtr accountName, 
    UInt32 maxLength, 
    void *passwordData, 
    UInt32 *actualLength, 
    KCItemRef *item
);

serviceName: A pointer to a Pascal string containing an application-defined service name. Pass NULL to match any service name.
accountName: A pointer to a Pascal string containing an application-defined account name. Pass NULL to match any account name.
maxLength: The length of the buffer pointed to by passwordData. Pass 0 if you want to obtain the item reference but not the password data. In this case, you must also pass NULL in the passwordData parameter.
passwordData: A pointer to a buffer which will hold the returned password data. Before calling KCFindGenericPassword, allocate enough memory for the buffer to hold the data you want to store. Pass NULL if you want to obtain the item reference but not the password data. In this case, you must also pass 0 in the maxLength parameter. On return, a pointer to the returned password data.
actualLength: On return, the actual length of the password data that was retrieved. If the buffer pointed to by passwordData is smaller than the actual length of the data, KCFindGenericPassword returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling KCFindGenericPassword again.
item: On return, a pointer to a reference to the found item. Pass NULL if you don’t want to obtain this reference.

function result: A result code. The result code errKCNoDefaultKeychain indicates that no default keychain was found. The result code errKCItemNotFound indicates that no matching password item was found. The result code errKCBufferTooSmall indicates that your application must allocate a new buffer of sufficient size before calling KCFindGenericPassword again.

DISCUSSION

The KCFindGenericPassword function finds the first generic password item which matches the attributes you provide. The buffer specified in the passwordData parameter must be large enough to hold the password data, otherwise KCFindGenericPassword returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling KCFindGenericPassword again. KCFindGenericPassword optionally returns a reference to the found item.

VERSION NOTES

Available beginning with Keychain Manager 1.0. In Keychain Manager 1.0, the kcfindgenericpassword function provides the same functionality as KCFindGenericPassword, except that it accepts C strings rather than Pascal strings as arguments. In Keychain 2.0, you should use KCFindGenericPassword, since kcfindgenericpassword is provided for convenience only and may be removed from the header file at some point in the future.

AVAILABILITY

Under evaluation for Carbon. Available in CarbonLib 1.0 and later when KeychainLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by KeychainLib 1.0 and later.